Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
Removal of Persistent Object
Removal vs Release
A persistent object has two states -- a persistent state and a runtime state. The persistent state is stored in the associated storage unit while the runtime state is stored in the corresponding object instance.
When an object is released, only the runtime state is affected. For example, when the refcount of a persistent object goes down to 0 and is deleted, only the runtime state is destroyed while the persistent state remains unchanged.
However, when an object is removed, both the runtime and the persistent state are destroyed. That means the object instance and the storage unit will cease to exist.
Removal without using Draft API
Even though OpenDoc provides API to remove persistent objects created by the draft, a part editor does not need to remove any persistent objects using this API. This is because the underlying container suite is responsible for garbage collecting storage units that are no longer in use. A storage unit is not in use when it is no longer transitively strongly referenced by the draft properties storage unit.
Therefore, in order to remove a persistent object, all the part editor needs to do is to break or remove its reference to the storage unit of the persistent object.
// Focus to the value where the reference is to be removed.
partSU->Focus(...);
// remove the storage unit ref
partSU->RemoveStorageUnitRef(ev, ref);
The garbage collection scheme is completely dependent on the container suite. Therefore, make sure that you write out references to the storage units of all of the desired persistent objects during Externalize.
Removal using OpenDoc API
There are times when a part wants to remove a persistent object explicitly without relying on garbage collection. Here are a couple of examples:
- Two parts are tightly coupled. A part which is the creator and the sole client of a persistent object may choose to remove it at a particular time.
- A part may decide to remove a persistent object explicitly due to security reason. (However, one should note that security level provided depends on the container suite implementation.)
Using the ODDraft API does not guarantee a successful removal. If the persistent object has a refcount of more than 1 when Remove is called, an exception will be thrown. It is the client’s responsibility to anticipate and respond to the exception.
The following is a simple code fragment on the API usage:
